Moved and expanded project layout

diff --git a/src/doc/guide.md b/src/doc/guide.md
index 466b446d1e365927a20a6d55ad445eda8dd7a24b..9e9f5cc55a5234f61ccec9426d16e24494a8b02f 100644 (file)
--- a/src/doc/guide.md
+++ b/src/doc/guide.md
@@ -20,8 +20,8 @@ To accomplish this goal, Cargo does four things:
 You can convert an existing Rust project to use Cargo. You'll have to create a
 `Cargo.toml` file with all of your dependencies, and move your source files and
 test files into the places where Cargo expects them to be. See the [manifest
-description](manifest.html) and the "Cargo Conventions" section below for more
-details.
+description](manifest.html) and the [Project Layout](#project-layout) section
+below for more details.
 
 # Creating A New Project
 
@@ -199,17 +199,46 @@ source = "git+https://github.com/bjz/color-rs.git#bf739419e2d31050615c1ba1a395b4
 Now, if `color-rs` gets updated, we will still build with the same revision, until
 we choose to `cargo update` again.
 
-# Cargo Conventions
-
-Cargo uses conventions to make it easy to dive into a new Cargo project. Here
-are the conventions that Cargo uses:
-
-* `Cargo.toml` and `Cargo.lock` are stored in the root of your project.
-* Source code goes in the `src` directory.
-* External tests go in the `tests` directory.
-* The default executable file is `src/main.rs`.
-* Other executables can be placed in `src/bin/*.rs`.
-* The default library file is `src/lib.rs`.
+# Project Layout
+
+Cargo uses conventions for file placement to make it easy to dive into a new
+Cargo project. 
+
+`Cargo.toml` is kept in the root directory, as is `Cargo.lock`.
+
+If your project is an executable, name the main source file `src/main.rs`. If it
+is a library, name the main source file `src/lib.rs`. Cargo can create either of
+these automatically with `cargo new --bin` or `cargo new`.
+
+## Optional Components
+
+ * `src/bin/`: Other executables, to be built by default with 
+    `cargo build`
+ * `examples/`: Examples of usage, built with `cargo test` or `cargo build 
+    --example NAME`
+ * `tests/`: Integration tests, built and run with `cargo test`
+ * `benches/`: Benchmarks, built and run with `cargo bench`
+ 
+These are explained in more detail in the [manifest
+description](manifest.html#examples), but for now, here is an example directory
+layout:
+
+```notrust
+Cargo.toml
+Cargo.lock
+▾ src/          # directory containing source files
+  lib.rs        # the main entry point for libraries and packages
+  main.rs       # the default file for a project producing an executable
+  *.rs          # other modules
+  ▾ bin/        # (optional) directory containing executables
+    *.rs
+▾ examples/     # (optional) examples of library usage
+  *.rs
+▾ tests/        # (optional) integration tests
+  *.rs
+▾ benches/      # (optional) benchmarks
+  *.rs
+```
 
 # Cargo.toml vs Cargo.lock
 

diff --git a/src/doc/manifest.md b/src/doc/manifest.md
index 86a38cfbd019b18832a130a0ff61eba9ce0f435d..4f37468000291e97086799e72fa36c5f0b2f40e4 100644 (file)
--- a/src/doc/manifest.md
+++ b/src/doc/manifest.md
@@ -365,35 +365,11 @@ tests and benchmarks.
 These dependencies are *not* propagated to other packages which depend on this
 package.
 
-# The Project Layout
-
-If your project is an executable, name the main source file `src/main.rs`.
-If it is a library, name the main source file `src/lib.rs`.
-
-Cargo will also treat any files located in `src/bin/*.rs` as
-executables.
-
-When you run `cargo build`, Cargo will compile all of these files into
-the `target` directory.
-
-```notrust
-▾ src/          # directory containing source files
-  ▾ bin/        # (optional) directory containing executables
-    *.rs
-  lib.rs        # the main entry point for libraries and packages
-  main.rs       # the main entry point for projects producing executables
-▾ examples/     # (optional) examples
-  *.rs
-▾ tests/        # (optional) integration tests
-  *.rs
-▾ benches/      # (optional) benchmarks
-  *.rs
-```
-
 # Examples
 
-Files located under `examples` are example uses of the functionality
-provided by the library.  When compiled, they are placed in the
+Files located under `examples` are example uses of the functionality provided by
+the library (see [the guide](guide.html#project-layout) for a further
+description of standard project layout).  When compiled, they are placed in the
 `target/examples` directory.
 
 They must compile as executables (with `main.rs`) and load in the